/*
 * Copyright 2011-2012 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.sabayframework.activity;

/**
 * Activity is an abstraction of CPU-bound load. Implementor should define 'execute' method 
 * that should read available data elements from the input channel, compute result and then 
 * write the result into the output channel. Activity should avoid invoking synchronized or blocking
 * methods. isReady method signals to the framework that activity can be executed 
 * without any blocking.  
 * Usually activity methods are called as shown in the following pseudo code:
 * <pre> 
 *	ActivityContext ctx = ...
 *	beforeExecute(ctx);
 *	do {
 *	  if( isReady(ctx) ) execute(ctx);
 *	} while( !isDone(ctx) );
 *	afterExecute(ctx);
 * </pre>
 * @author Alex Antonau
 * */
public interface Activity<I,O> {
	
	/**
	 * Activity body.
	 * */
	void execute(ActivityContext<I, O> ctx) throws Exception;
	
	/**
	 * Called before this activity is executed in given context.
	 * */
	void beforeExecute(ActivityContext<I, O> ctx) throws Exception;
	
	/**
	 * Called after this activity was executed in given context.
	 * */
	void afterExecute(ActivityContext<I, O> ctx) throws Exception;
	/**
	 * Fast check whether this activity is ready to run. 
	 * @return returns true if this activity is ready to be executed in 
	 * given context, false - otherwise.
	 * */
	boolean isReady(ActivityContext<I, O> ctx) throws Exception;
	/**
	 * Fast check whether this activity has finished.
	 * @return returns true if this activity is completed in given context.
	 * */
	boolean isDone(ActivityContext<I, O> ctx) throws Exception;
	
	@Override
	int hashCode();
	
	@Override
	boolean equals(Object other);
	
}
